Mozahler

I've already discussed The Three Main Datatypes and how the Theme object provides processing hooks that are called during the build/run process.

Part of the appeal (to me) of the Website object is that by maintaining this implicit structure you can get the compiler to check your work and make sure that your work is consistent and complete.

It's greate to have some assurance that the pieces you are using are the correct ones (that they fit together, at least), and that all the components you've designated as required have been properly defined.

If you know that a post is always going to be associated with a date (many develop sites that aren't data-centric - so this is not a given), then you will want date to be a property that you can count on being available. Why not make date a property of your ItemMetadata object?

Metadata

possible examples of ItemMetadata use, and the purpose of requiring it up front.

Sometimes the Tail Wags the Dog

The rippling effect of changes made after the initial setup/the wisdom of organizing your project before making changes to the existing (working) initial setup. Do I want to bubble the changes up or push them down?

Before beginning to build up your site it makes sense to decide the layout. In the most general, broadest sense, we know we have a bunch of files and may need to present some of them in more than one way. Some websites emphasize a reverse-chronological approach (newest item at the top). So a date property is going to be important. Similarly, the name of the article could be the file name. Except maybe you don't want to rename your files if you find your focus within the file changing while setting up.

One of the conventions built into the Website definition and well-supported by the provided tools, is the "Front End YAML" code placed at the top of each file. (YAML - Yet Another Markup Language)

take a look at this:

---
date: 2018-11-06
title: Midterms
tags: midterms2018
excerpt: This is typically the opening paragraph of an article.
---

DRY

The developer who used this set of properties populated his index file with "cells" (or rows) that incorporated these excerpts right along with the title, date and tag. I'm not a particular fan of this approach because it means if I update the article, perhaps changing its focus in the process, the summary may get out of sync. Think of how some stale comments can remain after you've changed the code base - to fix a bug, for example. Not to mention that I'm copying and pasting something that I've already written.

Let's assume that the excerpt property is meant to summarize the content of the page without repeating the title. I have a few choices here: I can write an introductory paragraph that is presented with the full page, or I can write a chunk of text that only appears in the .excerpt property of this metadata. Maybe neither of those approaches makes sense to you.

Perhaps you have adopted a specific way to format your page - maybe you introduce each page with a summary paragraph using two hastags. You can have the opening paragraph display on the index page (the blog item) as well as serve as the opening paragraph of the page once it has been tapped. You would accomplish this by using a PublishingStep.

You're free to configure things your way.

Customizing the Site

I want to start off with a simple example.
Using plugins is one way to customize your site.

Here's what my build log looks like in Xcode when I run my package after a build

Publishing Wednesday (7 steps)
[1/7] Install plugin 'Splash'
[2/7] Copy 'Resources' files
[3/7] Add Markdown files from 'Content' folder
[4/7] Sort items
[5/7] Generate HTML
[6/7] Generate RSS feed
[7/7] Generate site map
✅ Successfully published Wednesday
Program ended with exit code: 0

All of this happens due to this small bit of code:

do {
    try Wednesday().publish(
        withTheme: .original,
        plugins: [.splash(withClassPrefix: "")]
    )
} catch {
    print(error)
    print(error.localizedDescription)
}

or if you prefer to see it on just one line:

     try Wednesday().publish(withTheme: .original, plugins: [.splash(withClassPrefix: "")]

Not only does this handle all my markdown files as well as .pngs and .gifs, but it even colorizes my embedded swift code, thanks to the use of the plugin. I didn't just add the reference to the plugin here and deploy my site. There's a little bit more to it than that. But installing a plugin is surprisingly straightforward - it's a simple edit to the Package.swift file. I will cover it in a separate blog post.

Customization encompasses a lot of possibilities. In the previous blog entry I mentioned PublishingSteps as a way to process your content. Customization is not only about content, but also appearance. What color schemes and fonts am I going to use? How do I make these changes happen? How do I want to present my story to the world? Customization also means automating pieces of the process to make it easier to add to your site as time goes on.

Links